fix(mcp): validate_expression takes the flow's declared variables at a flow condition - #33255

Fixes #33176

Clause-②: yes (widening) — validate_expression gains an optional input, variables, carrying the flow's declared variables at site: 'flow_condition', so the tool accepts a call it refuses today (strictToolInput); with no variables the answer is unchanged.
Metadata-protocol: none
Skills-docs: follow-up #33272

维护者速读

• 改了什么:MCP validate_expression 在 flow_condition 位点新增可选入参 variables(流程声明的变量,形状即 spec 的 FlowVariableSchema)。给了它,探针流程声明这些变量,运行时流程门禁自己的"变量遮蔽同名字段"告警会回来;共享校验器把这些裸名当变量,不再按字段判类型。
• 为什么改:流程运行时先绑定声明的变量、再平铺记录字段,所以与字段同名的裸名读到的是变量;工具此前拿不到变量,会按字段给出类型判定,也给不出门禁的遮蔽告警,代理保存流程时才看到不同的答案。
• 风险与回滚:只加一个可选入参;不传时每个调用的答案与之前逐字相同(既有 72 个工具级用例不改动即为对照);门禁接受集不变。回滚即 revert 本 PR。
• 先看:packages/lint/src/authored-site-expression.ts(authoredFlowProbe 声明变量)、packages/mcp/src/mcp-http-tools.ts(variables 入参、非流程位点拒收、flowVariables 提示、gatePassFindings 传参)。
• 两分钟验证:pnpm --filter @objectstack/mcp exec vitest run src/mcp-validate-expression.test.ts,预期 77 个测试全过,其中 title * 2 > 10 带 variables 时无类型错误且得到门禁的遮蔽告警,不带时报 type-mismatch-run-fails。
• 需要你做的:无,席位落地。

What changes

Input shape: an optional variables input, not "read from a named served flow". I chose the input. At a flow condition the tool reads only the subject object's served definition. Reading a named flow would need a new bridge member on both doors (the runtime bridge and the stdio bridge), a permission fence for flow metadata, and an answer for a flow that is not saved yet, which is the usual case while an agent authors one. That is outside this claim's file surface. The input takes the flow's own shape, z.array(FlowVariableSchema) from @objectstack/spec/automation, so an agent can hand over a flow's variables array as it stands. A malformed variable gets the spec's own refusal (a missing type, a $ name, an alias key such as input). No new shape is written by hand, which follows the AggregationNodeSchema precedent on aggregate_records.

With variables at site: 'flow_condition':

• Gate half. gatePassFindings hands the variables to judgeAuthoredSiteExpression, and authoredFlowProbe declares them on the one-flow probe. The gate's own walk then runs warnShadowedFieldReads on the probe's edge and gives its warning for a variable named like a field of objectName that is read bare. ⛔ Nothing is re-implemented: the probe only declares what the flow declares.
• Validator half. The shared validator gets the names through its existing option ExprSchemaHint.flowVariables, the key the gate hands it on the same flow. A bare read of a declared variable is therefore not typed as the field. "Typed as the variable" means what it means at the gate: the bare name stays dyn. Neither the gate nor the validator types a variable by its declared type, so the tool does not either.
• record.FIELD still reads the field and is judged as before.

Without variables nothing changes. The probe carries no variables key and the hint carries no flowVariables key, so every call answers byte for byte as before. The tool description and the input description say that the shadowed-read warning needs the variables.

variables on any other site is refused, as startCondition is: `variables` describes a flow; it applies only with site "flow_condition".

stdio. Measured: both transports register one tool definition through wireBridgeTools, and the stdio bridge already serves servedObjectDefinitionOf. So stdio-data-bridge.ts needs no change. A parity pin drives a real StdioServerTransport and the HTTP door with the same arguments.

Measured against the dispatch's mechanism notes (on origin/main 295ce127):

• The input schema took objectName, expression, site, severity, triggerKind, sweepObject, startCondition, field. Holds.
• The probe declared no variables. Holds; the module header said so.
• Does the validator have an option for extra bindings? Yes: flowVariables, names only. It does not type a variable at all, so a bare variable is left untyped rather than typed by the variable's type.
• Does stdio serve the same definition? Yes, as described above.

Tests

• packages/lint/src/authored-site-expression.test.ts (50 → 57)
  • The flow-condition table. warnShadowedFieldReads moves from pass-silent-here to pass. Its fixture now carries variables, and the entry is pinned equal to the runtime gate at the start, decision and edge slots of a hand-written flow that declares the same variables (+2 slot cases).
  • New block with the flow's declared variables (#33176) (+5):
    • the probe declares the variables as handed, and has no variables key without them;
    • CONTROL: without variables the gate and the entry both say nothing;
    • a variable that shadows no field gets no warning;
    • only the bare read is warned, and record.title is not;
    • every trigger kind, and a condition after a start condition, answers as the gate.
• packages/mcp/src/mcp-validate-expression.test.ts (72 → 77)
  • (a) Variable title shadows the text field title, read bare in title * 2 > 10. The tool's whole verdict, validator half included, equals the gate's verdict on a flow declaring it: one shadowed-read warning, no errors, ok: true. The finding names title and gp_req.
  • (b) CONTROL, the same call without variables: ok: false with type-mismatch-run-fails, the bare name typed as the field, equal to the definition-less bridge's answer.
  • The warning is the gate's after a startCondition too.
  • (d) A variable that shadows no field (threshold) gets [true, [], []], as at the gate.
  • The spec's own variable refusals: a missing type, $record, the alias input.
  • (c) The refusal table gains three rows: variables at validation, at template and at the default site.
• packages/mcp/src/mcp-stdio-tools.test.ts (18 → 20): the same variables input schema is advertised on stdio and HTTP. The shadowed call, the CONTROL call and the off-site refusal each give the same tools/call result on both transports, and the three answers differ as the input says they should.

Acceptance notes

• The validator half is handed the declared variables, not every name the run binds. On a real flow the gate also leaves node ids, screen field names and the engine's own names (record, previous, vars, current_user) untyped. The tool is handed what the flow declares under variables, so a bare name that one of those others holds is still typed as the field here. The gate's shadowed-read warning reads declared variables only, so that warning is exact.
• type is required by the spec's shape and read by neither half, the same as at the gate.
• Ruling grep (ruling|Ruling-ref|maintainer|⛔|#33147|#32872) in the touched functions:
  • authored-site-expression.ts: one binding line, "⛔ Nothing here re-implements a pass", which this change keeps. Every other hit is a provenance tag.
  • The validate_expression handler and gatePassFindings in mcp-http-tools.ts: no ruling, maintainer or ⛔ line, and 10 provenance tags.
  • No maintainer ruling on mcp: validate_expression at flow_condition judges a bare name without the flow's variables, so its type verdict and the door's shadowed-read warning can differ from the runtime flow door #33176.
• Serial constraint with fix(lint)!: os build and the object_extension publish door judge each validation rule an object extension adds by the object's own rule pass #33205 (draft, An object extension's validations are judged at neither the publish door nor os build, yet the registry registers them on the target object #33154). I read its diff at head 9d07ffa0. It touches authored-site-expression.test.ts at lines 103–153 (walkPushes, CYCLE) and validate-expressions.ts. This PR touches that test file only at lines 455–780 and does not touch validate-expressions.ts, so no hunk is shared.
• The header of authored-site-expression.ts said the shadowed-read warning never fires through the entry. It now says the warning fires when the variables are given, and does not fire, as before, when they are not.

Verification

Head 4cae1f45ab (origin/main 295ce127 plus two commits). Every reading below was taken at that head.

os-verify-lock: pnpm --filter @objectstack/lint --filter @objectstack/mcp run test
packages/lint test:  Test Files  208 passed (208)   Tests  8877 passed (8877)
packages/mcp test:   Test Files  64 passed (64)     Tests  1174 passed (1174)
VERDICT command-exit 0
os-verify-lock: pnpm --filter @objectstack/lint --filter @objectstack/mcp run typecheck
packages/lint typecheck$ tsc --noEmit && pnpm check:test-typecheck
packages/mcp typecheck$ tsc --noEmit && pnpm check:test-typecheck
VERDICT command-exit 0
pnpm lint (eslint . --no-inline-config) :: exit 0

L1  lint: the probe declares no variables (the `variables` spread in authoredFlowProbe deleted)
      lint suite reads src: 6 failed | 51 passed (57) — the 3 warnShadowedFieldReads slot cases,
      the probe read-back, the bare-read-only case, the trigger-kind/start-condition case
A1  mcp: the validator hint loses `flowVariables`
      1 failed | 96 passed (97) — "given the flow's variables, a bare read of one is the variable"
A2  mcp: `variables` not handed to the gate
      3 failed | 94 passed (97) — the whole-verdict pin, the start-condition pin, the stdio parity pin
A3  first attempt void: deleting the `if` line alone left a syntax error, no tests ran. Re-done as A3b:
A3b mcp: the off-site refusal disabled (`if (false)`)
      2 failed | 95 passed (97) — the refusal table, the stdio parity pin

dispatch-gates: gate list derived from the tree of 'objectstack-ai/objectstack' at commit 4cae1f45ab
65 families :: exit 0
pnpm check:dual-build-cjs-loads :: exit 3   PREREQUISITE NOT MET (no full build here) — NOT MEASURED, CI's Lint & Repo Gates runs it
pnpm check:lean-entry-closure   :: exit 3   PREREQUISITE NOT MET (objectql dist absent) — NOT MEASURED, same
✓ dispatch-gates --ran: 67 derived famil(ies) accounted for — 65 run, 2 NOT-MEASURED (2 DERIVED from a recorded exit 3).

Generated by Claude Code